package rolesystem.core;

/**
 * This interface allows to act within the role system, without being
 * registered.
 */
public interface RoleSystem
{
	/**
	 * Asks to system to be registered, requesting a specified role to be
	 * assigned.
	 * @param role Role to assign to registration.
	 * @return The instance that allows to act within the role system,
	 * being registered.
	 */
	public RoleRegistration reqRegistration(String role) throws
		RoleException;


	/**
	 * Asks to server to search for all registrations a specified role is
	 * assigned to.
	 * This method returns as soon as at least one suitable registration is
	 * found.
	 * @param role Role that must be assigned to registrations.
	 * @return An array filled with the identifiers of found registrations.
	 */
	public int[] searchForRole(String role) throws RoleException;


	/**
	 * Asks to server to search for all registrations a specified role is
	 * assigned to.
	 * This method returns as soon as at least one suitable registration is
	 * found or the specified timeout expires.
	 * @param role Role that must be assigned to registrations.
	 * @param timeout The maximum time to wait, in milliseconds; if it is
	 * 0, this method behaves like the one without timeout.
	 * @return An array filled with the identifiers of found registrations;
	 * if no suitable registration is found, the array has length equal to
	 * 0.
	 */
	public int[] searchForRole(String role, long timeout) throws RoleException;


	/**
	 * Asks to server to search for all registrations a specified role is
	 * assigned to.
	 * This method returns immediately.
	 * @param role Role that must be assigned to registrations.
	 * @return An array filled with the identifiers of found registrations;
	 * if no suitable registration is found, the array has length equal to
	 * 0.
	 */
	public int[] searchForRoleNoWait(String role) throws RoleException;
}
